.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PWRITE 3PROC
.Os
.Sh NAME
.Nm Pwrite
.Nd write data to the address space of a process
.Sh LIBRARY
.Lb libproc
.Sh SYNOPSIS
.In libproc.h
.Ft ssize_t
.Fo Pwrite
.Fa "struct ps_prochandle *P"
.Fa "const void *buf"
.Fa "size_t nbyte"
.Fa "uintptr_t address"
.Fc
.Sh DESCRIPTION
The
.Fn Pwrite
function writes data from
.Fa buf
to the process handle
.Fa P
starting at the address
.Fa address .
It writes at most
.Fa nbyte
of data.
The
.Fn Pwrite
function is logically analogous to the
.Xr pwrite 2
function.
.Pp
For live processes, this function is equivalent to writing to the
/proc file system
.Sy as
file for the process.
For core files, it writes to the logical address space of what was once the
process and not the corresponding offset in the on-disk file.
ELF objects grabbed through
.Xr Pgrab_file 3PROC
do not support being written to.
.Pp
The
.Fn Pwrite
function cannot be used to
.Em extend
the size of a mapping; writing to an unmapped region generates an
error.
.Sh RETURN VALUES
Upon successful completion, the
.Fn Pwrite
function returns the number of bytes successfully written to
.Fa P .
This number is never greater than
.Fa nbyte .
Otherwise, it returns
.Sy -1
and
.Sy errno
is set to indicate an error.
For the full list of errors see the
.Sy DIAGNOSTICS
section in
.Xr proc 5
and
the
.Sy ERRORS
section in
.Xr pwrite 2 .
.Pp
In addition, the
.Fn Pwrite
function will fail if:
.Bl -tag -width Er
.It Er EIO
.Fa P
refers to an ELF object and not a core file or active process.
.El
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr pwrite 2 ,
.Xr libproc 3LIB ,
.Xr proc 5
